Frontendová API brána: GraphQL Federation a Schema Stitching

Vo svete vývoja moderných webových aplikácií môže byť správa dát z viacerých zdrojov významnou výzvou. Ako aplikácie rastú na zložitosti a osvojujú si architektúry mikroslužieb, potreba zjednoteného a efektívneho spôsobu prístupu k dátam sa stáva prvoradou. Frontendová API brána funguje ako centrálny vstupný bod pre klientske aplikácie, agreguje dáta z rôznych backendových služieb a poskytuje zjednodušený zážitok pre vývojárov aj koncových používateľov. Tento blogový príspevok skúma dve výkonné techniky na budovanie frontendovej API brány: GraphQL Federation a Schema Stitching.

Čo je to frontendová API brána?

Frontendová API brána je architektonický vzor, kde dedikovaný server slúži ako sprostredkovateľ medzi frontendovými klientmi (napr. webovými prehliadačmi, mobilnými aplikáciami) a viacerými backendovými službami. Zjednodušuje získavanie dát tým, že:

• Agreguje dáta: Spája dáta z viacerých zdrojov do jednej odpovede.
• Transformuje dáta: Prispôsobuje formáty dát potrebám frontendu.
• Abstrahuje zložitosť: Skrýva zložitosť backendových služieb pred klientom.
• Presadzuje bezpečnosť: Implementuje politiky autentifikácie a autorizácie.
• Optimalizuje výkon: Ukladá často používané dáta do vyrovnávacej pamäte a znižuje počet sieťových požiadaviek.

V podstate implementuje vzor Backend for Frontend (BFF) vo väčšom meradle a umožňuje frontendovým tímom prevziať väčšiu kontrolu nad API, ktoré konzumujú. Vo väčších organizáciách môže správa a kurátorstvo vlastných API frontendom viesť k rýchlejšiemu dodávaniu a zníženiu závislosti od backendových tímov.

Prečo používať GraphQL pre frontendovú API bránu?

GraphQL je dopytovací jazyk pre API a runtime pre spracovanie týchto dopytov s vašimi existujúcimi dátami. Ponúka niekoľko výhod oproti tradičným REST API, čo ho robí vhodným na budovanie frontendových API brán:

• Efektívne získavanie dát: Klienti si vyžiadajú len tie dáta, ktoré potrebujú, čím sa znižuje nadmerné načítavanie (over-fetching) a zlepšuje výkon.
• Silné typovanie: GraphQL schémy definujú štruktúru dát, čo umožňuje lepšie nástroje a validáciu.
• Introspekcia: Klienti môžu objaviť dostupné dáta a operácie prostredníctvom introspekcie schémy.
• Schopnosti v reálnom čase: GraphQL subscriptions umožňujú aktualizácie dát v reálnom čase.

Využitím GraphQL môže frontendová API brána poskytnúť flexibilné, efektívne a vývojársky prívetivé rozhranie na prístup k dátam z viacerých backendových služieb. To je v ostrom kontraste s tradičnými prístupmi, ktoré používajú viacero REST koncových bodov, z ktorých každý musí byť dopytovaný jednotlivo a často vracajú viac dát, ako je potrebné.

GraphQL Federation: Distribuovaný prístup

Čo je GraphQL Federation?

GraphQL Federation je výkonná technika na budovanie distribuovaného GraphQL API skladaním viacerých GraphQL služieb (nazývaných "podgrafy") do jednej, zjednotenej schémy. Každý podgraf je zodpovedný za špecifickú doménu alebo zdroj dát a federačná brána orchestruje dopyty naprieč týmito podgrafmi.

Základný koncept sa točí okolo supergrafu, jedinej, zjednotenej GraphQL schémy, ktorá reprezentuje celé API. Tento supergraf je vytvorený skladaním menších GraphQL schém, nazývaných podgrafy, z ktorých každý reprezentuje špecifickú mikroslužbu alebo zdroj dát. Federačná brána je zodpovedná za smerovanie prichádzajúcich GraphQL dopytov na príslušné podgrafy a spájanie výsledkov do jednej odpovede.

Ako funguje GraphQL Federation

1. Definícia podgrafu: Každá mikroslužba vystavuje GraphQL API (podgraf), ktoré definuje jej vlastné dáta a operácie. Tieto schémy obsahujú direktívy, ktoré hovoria federačnej bráne, ako riešiť typy a polia. Kľúčové direktívy zahŕňajú `@key`, `@external` a `@requires`.
2. Kompozícia supergrafu: Federačná brána (napr. Apollo Gateway) získava schémy z každého podgrafu a skladá ich do jednej, zjednotenej schémy (supergrafu). Tento proces zahŕňa riešenie konfliktov typov a polí a vytváranie vzťahov medzi typmi naprieč rôznymi podgrafmi.
3. Plánovanie a vykonávanie dopytov: Keď klient pošle GraphQL dopyt bráne, brána analyzuje dopyt a určí, ktoré podgrafy je potrebné dopytovať na splnenie požiadavky. Následne distribuuje dopyt na príslušné podgrafy, zhromaždí výsledky a spojí ich do jednej odpovede, ktorá je vrátená klientovi.

Príklad: E-commerce platforma s GraphQL Federation

Zoberme si e-commerce platformu s oddelenými mikroslužbami pre produkty, zákazníkov a objednávky.

• Podgraf produktov: Spravuje informácie o produktoch (názov, popis, cena atď.).
• Podgraf zákazníkov: Spravuje dáta o zákazníkoch (meno, adresa, e-mail atď.).
• Podgraf objednávok: Spravuje informácie o objednávkach (ID objednávky, ID zákazníka, ID produktov, celková suma atď.).

Každý podgraf vystavuje GraphQL API a federačná brána skladá tieto API do jedného supergrafu. Klient potom môže dopytovať supergraf, aby získal informácie o produktoch, zákazníkoch a objednávkach v jedinej požiadavke.

Napríklad dopyt na získanie mena zákazníka a histórie jeho objednávok by mohol vyzerať takto:

query GetCustomerAndOrders($customerId: ID!) {
  customer(id: $customerId) {
    id
    name
    orders {
      id
      orderDate
      totalAmount
    }
  }
}

Federačná brána by tento dopyt smerovala na podgrafy Zákazníkov a Objednávok, získala by potrebné dáta a spojila by ich do jednej odpovede.

Výhody GraphQL Federation

• Zjednodušený prístup k dátam: Klienti interagujú s jediným GraphQL koncovým bodom bez ohľadu na podkladové zdroje dát.
• Zlepšený výkon: Získavanie dát je optimalizované získavaním len potrebných dát z každého podgrafu.
• Zvýšená škálovateľnosť: Každý podgraf môže byť škálovaný nezávisle, čo umožňuje lepšie využitie zdrojov.
• Decentralizovaný vývoj: Tímy môžu vyvíjať a nasadzovať podgrafy nezávisle, čo podporuje agilitu a inováciu.
• Správa schémy: Federačná brána vynucuje konzistenciu a kompatibilitu schémy naprieč podgrafmi.

Nástroje pre GraphQL Federation

• Apollo Federation: Populárna open-source implementácia GraphQL Federation, ktorá poskytuje bránu, register schém a nástroje na budovanie a správu federovaných GraphQL API. Apollo Federation je známa svojou škálovateľnosťou a robustným spracovaním chýb.
• GraphQL Hive: Tento nástroj ponúka register schém a správu pre federované GraphQL služby, poskytujúc funkcie ako detekcia zmien, analýza používania a kontroly schém. Zlepšuje viditeľnosť a kontrolu nad supergrafom.

Schema Stitching: Alternatívny prístup

Čo je Schema Stitching?

Schema Stitching je ďalšia technika na kombinovanie viacerých GraphQL schém do jednej, zjednotenej schémy. Na rozdiel od Federation, Schema Stitching zvyčajne zahŕňa manuálnejší proces definovania, ako sú typy a polia z rôznych schém prepojené. Hoci sa Federation považuje za modernejšie a robustnejšie riešenie, Schema Stitching môže byť životaschopnou možnosťou pre jednoduchšie prípady použitia alebo pri migrácii z existujúcich GraphQL API.

Ako funguje Schema Stitching

1. Definícia schémy: Každá mikroslužba vystavuje GraphQL API s vlastnou schémou.
2. Logika spájania (Stitching Logic): Vrstva na spájanie (často implementovaná pomocou knižníc ako GraphQL Tools) definuje, ako sú typy a polia z rôznych schém prepojené. To zahŕňa písanie resolver funkcií, ktoré získavajú dáta z podkladových služieb a mapujú ich na zjednotenú schému.
3. Zjednotená schéma: Vrstva na spájanie kombinuje jednotlivé schémy do jednej, zjednotenej schémy, ktorá je vystavená klientovi.

Príklad: Spájanie produktov a recenzií

Predstavte si dve samostatné GraphQL služby: jedna pre produkty a druhá pre recenzie.

• Služba produktov: Poskytuje informácie o produktoch (ID, názov, popis, cena).
• Služba recenzií: Poskytuje recenzie pre produkty (ID, ID produktu, hodnotenie, komentár).

Pomocou Schema Stitching môžete vytvoriť zjednotenú schému, ktorá klientom umožňuje získať informácie o produkte a recenzie v jedinom dopyte.

Definovali by ste resolver funkciu vo vrstve na spájanie, ktorá získa recenzie pre dané ID produktu zo Služby recenzií a pridá ich k typu Produkt v zjednotenej schéme.

// Example (Conceptual): Stitching logic using GraphQL Tools
const { stitchSchemas } = require('@graphql-tools/stitch');

const productsSchema = ... // Define your products schema
const reviewsSchema = ... // Define your reviews schema

const stitchedSchema = stitchSchemas({
  subschemas: [
    {
      schema: productsSchema,
    },
    {
      schema: reviewsSchema,
      transforms: [
        {
          transformSchema: (schema) => schema,
          transformRequest: (originalRequest) => {
            return originalRequest;
          },
          transformResult: (originalResult) => {
            return originalResult;
          }
        }
      ],
    },
  ],
  typeDefs: `
    extend type Product {
      reviews: [Review]
    }
  `,
  resolvers: {
    Product: {
      reviews: {
        resolve: (product, args, context, info) => {
          // Fetch reviews for the product from the Reviews Service
          return fetchReviewsForProduct(product.id);
        },
      },
    },
  },
});

Tento príklad demonštruje základný koncept spájania schém. Všimnite si potrebu vlastných resolverov na získanie poľa `reviews`. Táto dodatočná réžia kódovania resolverov pre každý vzťah môže spomaliť vývojový proces v porovnaní s použitím Federation.

Výhody Schema Stitching

• Zjednotené API: Klienti pristupujú k jedinému GraphQL koncovému bodu, čo zjednodušuje prístup k dátam.
• Inkrementálne prijatie: Schema Stitching môže byť implementované inkrementálne, čo vám umožňuje postupne migrovať na zjednotené API.
• Flexibilita: Schema Stitching poskytuje väčšiu kontrolu nad tým, ako sú schémy kombinované, čo vám umožňuje prispôsobiť logiku spájania špecifickým potrebám.

Nevýhody Schema Stitching

• Manuálna konfigurácia: Schema Stitching vyžaduje manuálnu konfiguráciu logiky spájania, čo môže byť zložité a časovo náročné.
• Výkonnostná réžia: Resolver funkcie môžu priniesť výkonnostnú réžiu, najmä ak zahŕňajú zložité transformácie dát.
• Obmedzená škálovateľnosť: Schema Stitching môže byť ťažšie škálovateľné ako Federation, pretože logika spájania je zvyčajne centralizovaná.
• Vlastníctvo schémy: Môže viesť k nejednoznačnosti ohľadom vlastníctva schémy, najmä ak rôzne tímy spravujú spojené služby.

Nástroje pre Schema Stitching

• GraphQL Tools: Populárna knižnica na budovanie a manipuláciu s GraphQL schémami, vrátane podpory pre Schema Stitching.
• GraphQL Mesh: GraphQL Mesh vám umožňuje používať dopytovací jazyk GraphQL na prístup k dátam z rôznych zdrojov, ako sú REST API, databázy a gRPC. Dokáže tieto API spojiť do zjednotenej GraphQL schémy.

GraphQL Federation vs. Schema Stitching: Porovnanie

Obidve, GraphQL Federation aj Schema Stitching, ponúkajú spôsoby, ako skombinovať viacero GraphQL schém do jedného API, ale líšia sa vo svojom prístupe a schopnostiach.

Vlastnosť	GraphQL Federation	Schema Stitching
Prístup	Distribuovaná, automatizovaná kompozícia	Centralizovaná, manuálna konfigurácia
Zložitosť	Nižšia zložitosť pri údržbe a škálovaní	Vyššia zložitosť kvôli manuálnej logike resolverov
Škálovateľnosť	Navrhnuté pre rozsiahle, distribuované systémy	Menej škálovateľné, typicky používané pre menšie aplikácie
Správa schémy	Vstavaná správa schémy a validácia	Vyžaduje manuálnu správu schémy a koordináciu
Nástroje	Silný ekosystém nástrojov a knižníc (napr. Apollo Federation)	Vyžaduje viac vlastných nástrojov a konfigurácie
Prípady použitia	Architektúry mikroslužieb, rozsiahle API, decentralizovaný vývoj	Menšie aplikácie, inkrementálna migrácia, špecifické požiadavky na prispôsobenie

Kedy použiť GraphQL Federation: Zvoľte Federation, ak máte zložitú architektúru mikroslužieb, potrebujete škálovať vaše API a chcete umožniť nezávislým tímom spravovať vlastné podgrafy. Taktiež zjednodušuje správu a riadenie schémy.

Kedy použiť Schema Stitching: Zvážte Schema Stitching, ak máte jednoduchšie API, potrebujete väčšiu kontrolu nad logikou spájania alebo migrujete z existujúcich GraphQL API. Buďte si však vedomí potenciálnych zložitostí a obmedzení škálovateľnosti.

Implementácia autentifikácie a autorizácie

Bez ohľadu na to, či si vyberiete GraphQL Federation alebo Schema Stitching, implementácia autentifikácie a autorizácie je kľúčová pre zabezpečenie vašej frontendovej API brány. Existuje niekoľko prístupov, ktoré môžete použiť:

• Autentifikácia na úrovni brány: API brána spracováva autentifikáciu a autorizáciu pred smerovaním požiadaviek na backendové služby. Tento prístup centralizuje bezpečnostnú logiku a zjednodušuje backendové služby. Bežné metódy zahŕňajú validáciu JWT (JSON Web Token) a OAuth 2.0.
• Autentifikácia na úrovni služby: Každá backendová služba spracováva vlastnú autentifikáciu a autorizáciu. Tento prístup poskytuje granulárnejšiu kontrolu nad bezpečnosťou, ale môže byť zložitejší na správu.
• Hybridný prístup: Kombinácia autentifikácie na úrovni brány a na úrovni služby. Brána spracováva počiatočnú autentifikáciu a backendové služby vykonávajú granulárnejšie autorizačné kontroly.

Príklad: JWT autentifikácia s Apollo Federation

S Apollo Federation môžete nakonfigurovať bránu tak, aby validovala JWT tokeny zahrnuté v hlavičkách požiadaviek. Brána potom môže poslať informácie o používateľovi extrahované z tokenu podgrafom, ktoré môžu tieto informácie použiť na autorizáciu.

// Example (Conceptual): Apollo Gateway configuration with JWT validation
const { ApolloGateway } = require('@apollo/gateway');

const gateway = new ApolloGateway({
  serviceList: [
    // ... your subgraph configurations
  ],
  buildService: ({ name, url }) => {
    return new MyCustomService({
      name,  // Name of the subgraph
      url,   // URL of the subgraph
    });
  },
});

class MyCustomService extends RemoteGraphQLDataSource {
  willSendRequest({ request, context }) {
    // Get the user from the context
    const user = context.user;

    // Add the user's ID to the request headers
    if (user) {
      request.http.headers.set('user-id', user.id);
    }
  }
}

V tomto príklade je vytvorená vlastná služba na úpravu odchádzajúcich požiadaviek tak, aby obsahovali ID používateľa odvodené z JWT. Následné služby (downstream) potom môžu použiť toto ID na autorizačné kontroly.

Stratégie cachovania pre optimalizáciu výkonu

Cachovanie je nevyhnutné na zlepšenie výkonu frontendovej API brány. Ukladaním často používaných dát do vyrovnávacej pamäte môžete znížiť zaťaženie backendových služieb a zlepšiť časy odozvy pre klientov. Tu sú niektoré stratégie cachovania:

• HTTP cachovanie: Využite mechanizmy HTTP cachovania (napr. hlavičky `Cache-Control`) na ukladanie odpovedí do cache v prehliadači a medziproxy serveroch.
• Cachovanie v pamäti: Použite cache v pamäti (napr. Redis, Memcached) na ukladanie často používaných dát na bráne.
• CDN cachovanie: Využite siete na doručovanie obsahu (CDN) na cachovanie statických aktív a odpovedí API bližšie ku klientovi.
• Cachovanie GraphQL dopytov: Ukladajte výsledky GraphQL dopytov na základe ich dopytovacieho reťazca a premenných. Toto môže byť obzvlášť efektívne pre často vykonávané dopyty. Apollo Server ponúka vstavanú podporu pre cachovanie dopytov.

Pri implementácii cachovania zvážte stratégie invalidácie cache, aby ste zabezpečili, že klienti dostanú aktuálne dáta. Bežné stratégie zahŕňajú:

• Expirácia na základe času: Nastavte pevný čas expirácie pre cachované dáta.
• Invalidácia na základe udalostí: Invalidujte cache, keď sa dáta v backendových službách zmenia. Toto je možné dosiahnuť pomocou webhookov alebo message queues.

Monitoring a pozorovateľnosť

Monitoring a pozorovateľnosť (observability) sú kľúčové pre zabezpečenie zdravia a výkonu vašej frontendovej API brány. Implementujte komplexný monitoring na sledovanie kľúčových metrík, ako sú:

• Latencia požiadaviek: Čas potrebný na spracovanie požiadavky.
• Chybovosť: Percento požiadaviek, ktoré skončia chybou.
• Priepustnosť: Počet spracovaných požiadaviek za jednotku času.
• Využitie zdrojov: Využitie CPU, pamäte a siete brány a backendových služieb.

Použite trasovanie (tracing) na sledovanie požiadaviek, ako prechádzajú systémom, a identifikujte úzke miesta a výkonnostné problémy. Logovanie poskytuje cenné poznatky o správaní brány a backendových služieb.

Nástroje pre monitoring a pozorovateľnosť zahŕňajú:

• Prometheus: Open-source systém pre monitoring a alerting.
• Grafana: Nástroj na vizualizáciu dát a monitoring.
• Jaeger: Open-source systém pre distribuované trasovanie.
• Datadog: Platforma pre monitoring a bezpečnosť cloudových aplikácií.
• New Relic: Platforma digitálnej inteligencie pre monitoring a zlepšovanie výkonu softvéru.

Implementáciou robustného monitoringu a pozorovateľnosti môžete proaktívne identifikovať a riešiť problémy, čím zabezpečíte spoľahlivosť a výkon vašej frontendovej API brány.

Záver

Frontendová API brána postavená s GraphQL Federation alebo Schema Stitching môže výrazne zjednodušiť prístup k dátam, zlepšiť výkon a vylepšiť vývojársky zážitok v moderných webových aplikáciách. GraphQL Federation poskytuje výkonné a škálovateľné riešenie na skladanie distribuovaných GraphQL API, zatiaľ čo Schema Stitching ponúka flexibilnejší prístup na kombinovanie existujúcich schém. Dôkladným zvážením špecifických požiadaviek vašej aplikácie a kompromisov medzi týmito technikami si môžete vybrať najlepší prístup pre budovanie robustnej a efektívnej frontendovej API brány.

Nezabudnite implementovať správnu autentifikáciu a autorizáciu, stratégie cachovania a monitoring a pozorovateľnosť, aby ste zabezpečili bezpečnosť, výkon a spoľahlivosť vašej brány. Osvojením si týchto osvedčených postupov môžete odomknúť plný potenciál GraphQL a budovať moderné webové aplikácie, ktoré poskytujú výnimočné používateľské zážitky.